---
title: 'Built-in and Custom Reporters in Cypress: Setup Guide'
description: Learn how to use custom reporters in Cypress to output test results in different formats.
sidebar_label: Reporters
---

<ProductHeading product="app" />

# Reporters in Cypress

:::info

##### <Icon name="question-circle" color="#4BBFD2" /> What you'll learn

- How to use custom reporters in Cypress
- How to use multiple reporters
- How to merge reports across spec files

:::

## Introduction

After writing and running tests in Cypress, reviewing the results of those tests is crucial.
Cypress provides several options to review results of a test run.

- [Cypress Cloud](/cloud/get-started/introduction) - See test results, spec data, errors,
  screenshots, videos, and Test Replay in Cypress Cloud.
- Cypress App's open source built in and custom reporters.

This document covers how to use [built in](#Built-in-reporters) and [custom](#Custom-reporters) reporters in Cypress App.

:::tip

<CloudFreePlan />

:::

## Built in reporters

Because Cypress is built on top of Mocha, that means any reporter built for
Mocha can be used with Cypress. Here is a list of built in Mocha reporters.

- [Mocha's built-in reporters](https://mochajs.org/#reporters)

By default, Cypress uses the `spec` reporter to output information to `STDOUT`.

We've also added the two most common 3rd party reporters for Mocha. These are
built into Cypress and you can use them without installing anything.

- [`teamcity`](https://github.com/travisjeffery/mocha-teamcity-reporter)
- [`junit`](https://github.com/michaelleeallen/mocha-junit-reporter)

## Custom reporters

Cypress supports creating your own custom reporters or using any kind of 3rd
party reporter.

### Installed locally

You can load
[custom Mocha reporters](https://mochajs.org/api/tutorial-custom-reporter.html)
through a relative or absolute path. These can be specified in your Cypress
configuration file or via the [command line](/app/references/command-line).

For example, if you have the following directory structure:

```txt
> my-project
  > cypress
  > src
  > reporters
    - custom.js
```

You would specify the path to your custom reporter in either of the ways below.

#### Cypress configuration

:::cypress-config-example

```ts
{
  reporter: 'reporters/custom.js'
}
```

:::

#### Command Line

```shell
npx cypress run --reporter reporters/custom.js
```

### Installed via npm

When using custom reporters via npm, specify the package name.

#### Cypress configuration

:::cypress-config-example

```ts
{
  reporter: 'mochawesome'
}
```

:::

#### Command line

```shell
npx cypress run --reporter mochawesome
```

## Reporter Options

Some reporters accept options that customize their behavior. These can be
specified in your Cypress configuration or via
[command line](/app/references/command-line) options.

Reporter options differ depending on the reporter (and may not be supported at
all). Refer to the documentation for the reporter you are using for details on
which options are supported.

The below configuration will output the JUnit report to `STDOUT` and save it
into an XML file.

### Cypress configuration

:::cypress-config-example

```ts
{
  reporter: 'junit',
  reporterOptions: {
    mochaFile: 'results/my-test-output.xml',
    toConsole: true
  }
}
```

:::

### Command line

```shell
npx cypress run --reporter junit \
  --reporter-options "mochaFile=results/my-test-output.xml,toConsole=true"
```

## Merging reports across spec files

Each spec file is processed completely separately during each `cypress run`
execution. Thus each spec run _overwrites_ the previous report file. To preserve
unique reports for each specfile, use the `[hash]` in the `mochaFile` filename.

The following configuration will create separate XML files in the `results`
folder. You can then merge the reported output in a separate step using a 3rd
party tool. For example, for the
[Mochawesome](https://github.com/adamgruber/mochawesome) reporter, you can use
the [mochawesome-merge](https://github.com/antontelesh/mochawesome-merge) tool.

#### Cypress configuration

:::cypress-config-example

```ts
{
  reporter: 'junit',
  reporterOptions: {
    mochaFile: 'results/my-test-output-[hash].xml'
  }
}
```

:::

#### Command line

```shell
npx cypress run --reporter junit \
  --reporter-options "mochaFile=results/my-test-output-[hash].xml"
```

## Multiple reporters

Oftentimes we see users wanting the ability to use multiple reporters. When
running in CI, you might want to generate a report for `junit` and perhaps a
`json` report. This is great, but by setting this reporter you won't receive any
additional feedback while the tests are running!

The solution here is to use multiple reporters. You will have the benefit of
both worlds.

We suggest using the npm module [cypress-multi-reporters](https://www.npmjs.com/package/cypress-multi-reporters).

### Examples

#### Spec to `STDOUT`, save JUnit XML files

We want to output a `spec` report to `STDOUT`, while saving a JUnit XML file for
each spec file.

We need to install additional dependencies:

- [`cypress-multi-reporters`](https://github.com/YOU54F/cypress-plugins/tree/master/cypress-multi-reporters):
  enables multiple reporters
- [`mocha-junit-reporter`](https://github.com/michaelleeallen/mocha-junit-reporter)
  the actual junit reporter, as we cannot use the `junit` reporter that comes
  with Cypress

```shell
npm install cypress-multi-reporters mocha-junit-reporter --save-dev
```

Specify your reporter and reporterOptions in your Cypress configuration or via
the [command line](/app/references/command-line).

#### Cypress configuration

:::cypress-config-example

```ts
{
  reporter: 'cypress-multi-reporters',
  reporterOptions: {
    configFile: 'reporter-config.json'
  }
}
```

:::

#### Command line

```shell
npx cypress run --reporter cypress-multi-reporters \
  --reporter-options configFile=reporter-config.json
```

Then add the separate `reporter-config.json` file (defined in your
configuration) to enable `spec` and `junit` reporters and direct the `junit`
reporter to save separate XML files.

```json title="reporter-config.json"
{
  "reporterEnabled": "spec, mocha-junit-reporter",
  "mochaJunitReporterReporterOptions": {
    "mochaFile": "cypress/results/results-[hash].xml"
  }
}
```

We recommend deleting all files from the `cypress/results` folder before running
this command, since each run will output new XML files. For example, you can add
the npm script commands below to your `package.json` then call `npm run report`.

```json title="package.json"
{
  "scripts": {
    "delete:reports": "rm cypress/results/* || true",
    "prereport": "npm run delete:reports",
    "report": "cypress run --reporter cypress-multi-reporters --reporter-options configFile=reporter-config.json"
  }
}
```

In case you want to combine generated XML files into a single one,
[junit-report-merger](https://www.npmjs.com/package/junit-report-merger) can be
added. For example, to combine all files into
`cypress/results/combined-report.xml` the `combine:reports` script can be added.

```json title="package.json"
{
  "scripts": {
    "delete:reports": "rm cypress/results/* || true",
    "combine:reports": "jrm cypress/results/combined-report.xml \"cypress/results/*.xml\"",
    "prereport": "npm run delete:reports",
    "report": "cypress run --reporter cypress-multi-reporters --reporter-options configFile=reporter-config.json",
    "postreport": "npm run combine:reports"
  }
}
```

#### Spec to `STDOUT`, produce a combined Mochawesome JSON file

This example is shown in the branch `spec-and-single-mochawesome-json` in
[https://github.com/cypress-io/cypress-example-circleci-orb](https://github.com/cypress-io/cypress-example-circleci-orb).
We want to output a "spec" report to `STDOUT`, save an individual Mochawesome
JSON file per test file, and then combine all JSON reports into a single report.

We need to install some additional dependencies.

```shell
npm install mochawesome mochawesome-merge mochawesome-report-generator --save-dev
```

We need to configure the reporter in your
[Cypress configuration](/app/references/configuration) to skip the HTML
report generation and save each individual JSON file in the `cypress/results`
folder.

#### Cypress configuration

:::cypress-config-example

```ts
{
  reporter: 'mochawesome',
  reporterOptions: {
    reportDir: 'cypress/results',
    overwrite: false,
    html: false,
    json: true
  }
}
```

:::

#### Command line

```shell
npx cypress run --reporter mochawesome \
  --reporter-options reportDir="cypress/results",overwrite=false,html=false,json=true
```

Our run will generate files
`cypress/results/mochawesome.json, cypress/results/mochawesome_001.json, ...`.
Then we can combine them using the
[mochawesome-merge](https://github.com/antontelesh/mochawesome-merge) utility.

```shell
npx mochawesome-merge "cypress/results/*.json" > mochawesome.json
```

We can now generate a combined HTML report from the `mochawesome.json` file
using the
[https://github.com/adamgruber/mochawesome-report-generator](https://github.com/adamgruber/mochawesome-report-generator):

```shell
npx marge mochawesome.json
```

It generates the beautiful standalone HTML report file
`mochawesome-report/mochawesome.html` shown below. As you can see all test
results, timing information, and even test bodies are included.

<DocsImage
  src="/img/app/reporters/mochawesome-report.png"
  alt="Mochawesome HTML report"
/>

For more information, see
[Integrating Mochawesome reporter with Cypress's](http://antontelesh.github.io/testing/2019/02/04/mochawesome-merge.html)

## History

| Version                            | Changes                                                                                                                                         |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| [4.4.2](/app/references/changelog) | Custom Mocha reporters updated to use the version of Mocha bundled with Cypress. No need to install `mocha` separately to use custom reporters. |
